home *** CD-ROM | disk | FTP | other *** search
/ Amiga Games Extra 1996 September / Amiga Games Extra CD-ROM 9-1996.iso / userbox / publicdomain / prlink-0.9.5b / readme < prev    next >
Text File  |  1996-07-06  |  68KB  |  1,588 lines
  1. prlink v0.9.5b -- a data transfer system between Commodore 8-bit computers
  2.           and an Amiga (AmigaDOS) or a PC clone (Linux, MS-DOS)
  3.  
  4. Release date: 22nd May, 1996, 7 july 1996 for 0.9.5b with the Amiga
  5. files.
  6. Copyright © 1994-1996 Marko Mäkelä and Olaf Seibert
  7. Original Linux and Commodore 64/128/Vic-20/16 version by Marko Mäkelä
  8. Ported to the PET and the Amiga series by Olaf Seibert
  9.  
  10.     This program is free software; you can redistribute it and/or modify
  11.     it under the terms of the GNU General Public License as published by
  12.     the Free Software Foundation; either version 2 of the License, or
  13.     (at your option) any later version.
  14.  
  15.     This program is distributed in the hope that it will be useful,
  16.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  17.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18.     GNU General Public License for more details.
  19.  
  20.     You should have received a copy of the GNU General Public License
  21.     along with this program; if not, write to the Free Software
  22.     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  23.  
  24.  
  25. *NOTE*:    This version does not include any Amiga files, because Olaf Seibert
  26.     was too busy to adapt the Amiga sources.  An Amiga version will be
  27.     released later, probably before the next common release.
  28.     Ask Olaf <rhialto@mbfys.kun.nl> for the Amiga version.
  29.  
  30. [ Not so anymore -Olaf ]
  31.  
  32. 0. PREFACE
  33.  
  34. This document describes the prlink utility, a program package that lets you
  35. to transfer data over a parallel connection between a Commodore 8-bit
  36. computer and a bigger system (Amiga or PC).
  37.  
  38. The utility is based on a daemon, or a memory resident IRQ handler wedge
  39. running in the Commodore end of the cable.  You always issue the link
  40. commands from the other side (Amiga or PC).  This implementation saves you
  41. from needing a server process on the bigger computer, which is very
  42. important for MS-DOS users.
  43.  
  44. Currently daemons are available for the Commodore PET series (3032 and
  45. 8032/4032), the Vic-20, C64, C16 and C128 computers.  There are compilation
  46. options that support the Commodore REU (RAM Expansion Unit), even
  47. simultaneously with an Action Replay cartridge installed, and some internal
  48. memory expansions on the C64 and the C128.
  49.  
  50. The client programs are written so that they compile on Amiga and on Linux
  51. with the GNU utilities, and on MS-DOS with Visual C++, or with older versions
  52. of Microsoft C.  The programs were originally written for Linux.  The Linux
  53. and MS-DOS versions use machine language optimized transfer routines.  Also
  54. the Amiga version is partially manually optimized in 68000 machine language.
  55.  
  56. The idea of the transfer utility package is that a daemon runs on the
  57. Commodore side in an interrupt routine, without affecting the computer's
  58. performance.  It checks if the other side wants to send any command, and
  59. executes possible commands.  The protocol includes commands for memory
  60. transfers and for starting a machine language routine or a BASIC program.
  61. The latter two commands deinstall the daemon for maximum compatibility.
  62.  
  63. With the current protocol, it is possible to make useful applications that run
  64. on the other end, like disk and file copiers (prdisk, prrfile and prwfile),
  65. and possibly a machine language monitor.  It is already possible to develop
  66. Commodore programs on the other side, and to transfer them over to be tested
  67. out.  Actually, this is exactly how prlink itself has been developed.  On the
  68. Commodore 128, you can use a boot sector, so that the prlink daemon will be
  69. started automatically when you start the system.
  70.  
  71. We chose to use our "own" assembler, the DASM cross assembler, ported to ANSI
  72. C and extended by Olaf Seibert.  The assembler supports conditional
  73. assembling, relocated origins and macros.  You can retrieve it from
  74. ftp.funet.fi as /pub/cbm/programming/dasm.tar.gz.
  75.  
  76.  
  77. 1. GETTING STARTED
  78.  
  79. In order to save you from compiling the prlink binaries yourself, we have
  80. prepared binary distributions of prlink.  On Linux, it is normal to compile
  81. all software you get, but on the Amiga it is unusual to have a C compiler.
  82. Not to mention the MS-DOS environment, where it is almost impossible to get
  83. a free 8086 C compiler.
  84.  
  85. On MS-DOS, I chose Microsoft Visual C++, because it creates 8086 code, which
  86. runs on all PCs.  I could have used the GNU CC port, djgpp, but it only
  87. creates 80386 code.  And I assume most people who would have use for prlink in
  88. DOS would use Linux if it was possible.  (Linux requires at least 80386.)
  89.  
  90. There are two different binary distributions, one for AmigaDOS and one for
  91. MS-DOS.  Both of them include 6502 binaries for all supported machines and
  92. cables, and a native executable for all supported cables.  For Linux, there is
  93. no binary distribution available, since we want to encourage people to make
  94. their own modifications to prlink.
  95.  
  96. The source distribution is prlink-VERSION.tar.gz where VERSION is replaced
  97. with the prlink version number, like 0.9.5b.  It does not include any binaries,
  98. not even 6502 binaries.  Consult the "COMPILING" section of this document how
  99. to compile prlink.
  100.  
  101. The AmigaDOS binary distribution is called prlink-amiga-VERSION.lha where
  102. VERSION is the prlink version number.  Similarly, you can find the MS-DOS
  103. binary distribution under the name prlnkVRS.zip, e.g.  prlnk094.zip for the
  104. current version.
  105.  
  106. But beware, the MS-DOS version is merely a quick hack.  Although a hung
  107. transfer can now be stopped with Esc, there might be other bugs lurking
  108. around.  One known bug (or MS-DOS "feature") occurs when you redirect
  109. e.g. prsave output to a file (e.g. "prsave e000 0000 > kernal.prg".  A CR/LF
  110. conversion will take place, so this is not a reliable way to transfer
  111. binaries.  The same applies to prcart.
  112.  
  113.  
  114. 1.1 Bootstrapping
  115.  
  116. If you don't currently have any possibility to transfer data to your
  117. Commodore 8-bitter from other computers, don't worry.  In loader.bas, there
  118. is a BASIC loader with which you can download the prserver daemon to your
  119. computer.  Just type it in and save it on tape or disk before starting it.
  120.  
  121. On the other side, you need the prlink binaries.  The cable types (or
  122. transfer protocols) supported by the BASIC bootstrapper are the 4-bit/8-bit
  123. prlink cable, and the PC64 cable.
  124.  
  125. With a PC, you can choose either cable.  If you are not planning to use the
  126. PC64 emulator (currently the best Commodore 64 emulator for MS-DOS), you'd
  127. better choose the prlink cable because of its better overall performance.
  128.  
  129. On the Amiga, there is one native cable, which works with all supported
  130. protocols.  For the bootstrapping you can only choose the 4-bit/8-bit
  131. protocol, but you can use any protocol after you have transferred the desired
  132. daemon to the 8-bit Commodore side.  Furthermore there is the transnib
  133. protocol, which works over both TransNib and prlink cables.  The most
  134. efficient protocol is prlink88, which transfers 8 bits at a time in both
  135. directions.
  136.  
  137. Start the bootstrapper on your Commodore.  On the other side, change to the
  138. "bin" subdirectory and execute the prmain binary with the desired protocol
  139. to transfer the desired daemon to the Commodore, e.g.:
  140.  
  141.     linux/prmain -c prtrans4 --prload c64/prlink/prserver.prg
  142. or
  143.     amiga/prmain -c prlink --prload c64/prlink88/prserver.prg
  144. or
  145.     msdos\prmain -c prtrans4 --prload c64\pc64\prserver.prg
  146.  
  147. Now you should see a list of addresses and byte values scroll by.  If not,
  148. the connection does not work properly.  Ensure that the cable is properly
  149. connected and you have typed in the appropriate lines of the BASIC listing,
  150. so that it is adapted for your hardware.  Also, if you are using a PC, you
  151. may have chosen the wrong printer port.  Try the -p parameter with different
  152. numbers (from 0 to 3).  Also note that the Linux version requires super user
  153. (root) privileges.  Remember to install the software as root, or use "chown
  154. root" and "chmod u+s" on the binaries.
  155.  
  156. If everything seems to run correctly, replace the PRINT command on line 2050
  157. with POKE.  Now the prserver daemon will be really loaded to your computer.
  158. Once prserver.prg has been transferred, save it using your favourite method
  159. (an assembly language monitor is usually easiest).  The addresses it
  160. occupies are printed by the basic program.
  161.  
  162. Alternatively, if you have a disk drive, you can start the daemon and use
  163. the prwfile command to copy prserver.prg to disk.
  164.  
  165.  
  166. 1.2 Configuration
  167.  
  168. All prlink client programs are actually integrated into one program called
  169. "prmain" or something similar.  The prmain program chooses its function by
  170. the executable name, so you can make symbolic or hard links to prmain, if
  171. your system supports them.
  172.  
  173. For instance, if you rename or copy prmain to "prload", or make "prload" a
  174. symbolic link to it, it will function as described in Section 2.1.  The same
  175. function can be achieved by issuing the command "prmain --prload".  For this
  176. reason, you can also define a shell alias for prload, which makes sense if
  177. you want to use prlink with different cables and printer ports.
  178.  
  179. By default, the PC versions of prmain use the native prlink cable, and the
  180. Amiga version uses the prlink88 cable.  You can specify the protocol with
  181. the "-c" option on the command line.  If you are using some other protocol
  182. than these two, you are best off by defining aliases for the client
  183. programs.
  184.  
  185. For Linux, there are sample definitions in Start.tcsh and Start.bash.  As
  186. you might guess, one file is for tcsh and the other is for bash.  The
  187. scripts define environment variables for the file and disk transfer commands
  188. (see Section 2.4) and aliases for all client and protocol combinations.  The
  189. naming scheme is simple: function names combined with numbers indicating the
  190. protocol.  The X1541 cable is 1, the 64NET cable is 2, the PC64 cable is 4,
  191. and the prlink cable is 8.  Thus, "prload8" will execute the "prload"
  192. function using the prlink cable.  By the way, you should edit the "port"
  193. definitions in the scripts to set the parallel port numbers correctly.
  194.  
  195. In MS-DOS, you cannot define aliases, unless you are using DOSKEY or some
  196. other shell than COMMAND.COM.  Copying the executable under all six names
  197. would be a waste of disk space, and it doesn't even work, thanks to the
  198. brain-dead MS C runtime library.  But you can use batch files instead.  For
  199. instance, your PRLOAD.BAT might be as follows:
  200.  
  201.     @ECHO OFF
  202.     PRMAIN -c prtrans4 --prload -p 1 %1
  203.  
  204. You can define aliases in 4DOS or even in COMMAND.COM, if you use DOSKEY.
  205. For COMMAND.COM and DOSKEY, there is an example startup file in STARTDOS.BAT.
  206. Remember to make sure that the "port" setting is correct.
  207.  
  208. If you will be using prlink with one type of C= servers, e.g. you only have
  209. a C64, you don't need to to define the PRLINK environment variables, which
  210. saves environment variable space, which in turn consumes low memory.  In
  211. this case, you can use the -l option with prrfile, prwfile and prdisk.  See
  212. Section 2.4 for more details.
  213.  
  214.  
  215. 1.3 Usage
  216.  
  217. Start the 6502 side by giving the command
  218.  
  219.     SYS [start address]
  220.  
  221. where [start address] is of course the first byte of the program.  The server
  222. will hook itself in the IRQ handler chain and you should get a READY prompt
  223. back immediately.  Now you can use the prload, prsave, etc programs from the
  224. other side.  These programs give their usage if you call them with incorrect
  225. arguments (or no arguments at all).
  226.  
  227. To make the 6502 side remove itself from the IRQ chain, give the command
  228.  
  229.     SYS [start address + 3].
  230.  
  231. Note that the default VIC-20 version loads at 16384 ($4000).  This means
  232. that you need at least 16kB of expansion memory to use the program.  If you
  233. want to use prlink with an unexpanded VIC, you have to recompile the
  234. binaries.  But there won't really be much use for it, as the prserver daemon
  235. would eats up a big part of the unexpanded VIC's memory.
  236.  
  237. Now that you have successfully started the daemon on the 6502 side, you can
  238. start using the client programs, as described in the following section.
  239.  
  240.  
  241. 1.4 Automatic startup (C128 only)
  242.  
  243. The Commodore 128 tries to load a boot sector from device #8 in its startup
  244. routine.  With a special boot sector, it is possible to start the prserver
  245. daemon on the C128 automatically.  Marko has created such a boot sector.  It
  246. not only starts the prserver daemon for the C128; it can also switch to C64
  247. mode and start the prserver daemon there.  Also, it can switch off the PIA
  248. memory expansion (if any) for maximum compatibility.
  249.  
  250. By default, the boot sector loads the prserver daemon for C128 mode.  You
  251. can change this behaviour by holding a key down while the boot sector is
  252. being started.  Remember not to press the STOP or C= keys down too early,
  253. or the C128's startup routine doesn't load the boot sector.  The keys and
  254. their functions are as follows:
  255.  
  256.     Boot sector  Key pressed   File to load Mode  PIA support
  257.     ------------ ------------- ------------ ----  -----------
  258.     (both)       STOP          (none)       (aborts the boot)
  259.     bootsect.pia (none),<-,1,2 pr1028       C128  yes
  260.     bootsect.std (none),<-,1,2 pr128        C128  no
  261.     (both)       CTRL          pr128        C128  no (note 1)
  262.     bootsect.pia C=            pr2564       C64   yes
  263.         bootsect.std C=            pr64         C64   no
  264.     (both)       SPACE BAR     pr64         C64   no (note 1,2)
  265.     (both)       Q             (none)       C64   no (note 1,2)
  266.  
  267.     Note 1: bootsect.pia disables the PIA expansion in these modes.
  268.  
  269.     Note 2: The drive 8 will be issued the U0>M0 command in this case.
  270.             (Effectively, a 1571 drive will be reset to 1541 mode.)
  271.         The 40/80 key sense line will be zeroed in this case.
  272.         (This can be used to disable a ROM extension.  See text.)
  273.  
  274. The table may seem a bit chaotic for the first sight.  The column "file to
  275. load" is most important.  You have to copy the prserver daemons for the
  276. modes you use.  For instance, if you have a PIA expansion and a REU in your
  277. C128, and you are using the PC64 cable, you need to copy the following
  278. files:
  279.  
  280.     PC or Amiga filename        C128 filename
  281.     --------------------------  -------------
  282.     bin/c128/pc64/prserver.prg  pr128
  283.     bin/c128/pc64/prpiareu.prg  pr1028
  284.     bin/c64/pc64/prserver.prg   pr64
  285.     bin/c64/pc64/prpiareu.prg   pr2564
  286.     bin/c128/bootsect.pia       (must be copied to track 1, sector 0)
  287.  
  288. As you see, there are two different boot sectors to choose from.  Actually
  289. you could use bin/c128/bootsect.pia for everything, but then you would have
  290. to name the files accordingly.  The standard boot sector
  291. (bin/c128/bootsect.std) loads only pr128 or pr64, regarding to the selected
  292. operation mode.  The bootsector with PIA expansion support
  293. (bin/c128/bootsect.pia) can switch the PIA off, and load prserver daemons
  294. without any PIA support.
  295.  
  296. If you don't have any memory expansion, your choice is bootsect.std.  If you
  297. have the PIA expansion, the choice is bootsect.pia.  Actually, you can use
  298. this boot sector for any hardware configuration.  You can rename other
  299. programs to "pr128", "pr64", "pr1028" or "pr2564".  The boot sector makes a
  300. JSR to the start address of the program file.
  301.  
  302. You can copy the boot sector to the disk with prdisk, which is discussed in
  303. Section 2.4.3:
  304.  
  305.     prdisk -w bootsect.pia
  306.  
  307. You will get the error message "Could not read all of the input file."  This
  308. message can be safely ignored.
  309.  
  310. It is possible to change the default behavior of the bootsector.  As you can
  311. see from the source code in src/bootsect.a65, a default value will be loaded
  312. if none of the special keys is being pressed during the boot.  By changing
  313. the default value, you can create a boot sector that e.g.  automatically
  314. switches to C64 mode and loads the appropriate prserver daemon.  You can
  315. recompile the source with "make cleanchosen bootsect.prg".  Remember to cut
  316. the the two first bytes of the binary file (the loading address $0b00)
  317. before writing it to the disk, or make sure that the assembler is invoked
  318. with the option -f3.
  319.  
  320. If you have installed a custom KERNAL ROM (such as JiffyDOS) on the system,
  321. and you have two KERNALs (custom and standard) on the same EPROM, you can
  322. connect the KERNAL selection line to the 40/80 key.  If you do this, the
  323. C64 mode KERNAL can be selected simply with the 40/80 key.  But the bootsector
  324. can do the change as well.  If you press space to get to maximum compatibility
  325. C64 mode, the bootsector will pull the 40/80 key sense line low, which will
  326. select the standard KERNAL.
  327.  
  328.  
  329. 2. PROGRAMS
  330.  
  331. 2.1 prload
  332.  
  333. Prload loads a Commodore-style program file to the remote computer.  The
  334. program reports its usage as follows.
  335.  
  336.   prload: Uploads files to a memory area on a remote computer.
  337.  
  338.   Usage: prload [options] filename(s)
  339.   Options:
  340.     -a addr Override the load address from the file
  341.     -b bank Specify the memory bank (in hex)
  342.     -l    Load the file as BASIC.
  343.     -r    Performs the BASIC RUN command after the transfers.
  344.     -j addr Jumps to the specified hex address after the transfers.
  345.     -p port Specify the printer port (0 to 3)
  346.  
  347. As you see, you can load several files at once.  The -a option, which
  348. changes the program's loading address, only makes sense if you are loading a
  349. single file.  It is useful when loading BASIC programs that were written for
  350. different platform and thus have a different start address.  For loading
  351. BASIC programs, you can use the -l option as well.
  352.  
  353. A very useful feature is the -r option.  It deinstalls the prlink daemon
  354. after loading the program and performs the BASIC RUN command automatically.
  355. The -j option is similar, but it only works with machine language programs
  356. that do not end in an RTS.
  357.  
  358. The -p option selects the printer port on a PC.  You don't need this option
  359. if the default port number is suitable for you, as determined at compilation
  360. time.  The ports are numbered from 0 to 3, and they correspond to the port
  361. addresses $3bc, $378, $2bc and $278, respectively.
  362.  
  363. Last, but not least, the -b option chooses the memory bank, which is 0 by
  364. default.  It is only interpreted in the Commodore 128 version of the prlink
  365. daemon, and in versions compiled with support for any banked memory
  366. expansion.
  367.  
  368. Bank numbers 0 to f are for internal memory.  The two lowmost bits are for
  369. specifying the MMU mapped memory bank on a C128.  In other words, MMU mapped
  370. memory banks on the C128 are numbered from 0 to 3.  On unexpanded C128s, the
  371. banks 2 and 3 are the same than banks 0 and 1.
  372.  
  373. The bits 2 and 3 of the bank number specify the PIA mapped expanded memory
  374. bank on a C128 or a C64.  So, the 64kB banks of a C128 with 1 megabyte of
  375. internal memory are numbered from 0 to f.  On a 512kB-expanded C128, the
  376. unique bank numbers are 0-1, 4-5, 8-9 and c-d, as there are only two MMU
  377. banks.  For instance, the banks b and 9 are the same.  On a 256kB-expanded
  378. C64, or on a PIA-expanded C128 in C64 mode, the bank numbers 0-3, 4-7, 8-b
  379. and c-f are the same, so there are 4 different banks.
  380.  
  381. Bank numbers from 10 to ff are for REU memory banks, i.e. the banks of a
  382. 512-kilobyte-REU are numbered from 10 to 17.
  383.  
  384. As you can see from the prserver.a65 source code, the PIA and REU expansions
  385. are accessed through a 16kB window at $4000.  On a stock C128, the memory
  386. will be accessed through the FETCH ($2a2) and STASH ($2af) subroutines.  Due
  387. to their design, there's a bug in the plain C128 version: any data read from
  388. $0-$3ff will be fetched from bank 0.  The version for the PIA expansion does
  389. not have this bug.
  390.  
  391.  
  392. A typical prload command line looks like the following:
  393.  
  394.     prload -r sanxion
  395.  
  396. Note that the program to be loaded may not overwrite the prserver daemon
  397. code.  If this happens, the transfer will hang.  This is a bug, and in a
  398. later version we should relocate the prserver daemons to memory areas that
  399. are not used by normal programs, i.e. under I/O areas etc.
  400.  
  401.  
  402. 2.2 prsave
  403.  
  404. Prsave echoes the contents of a C= memory area to standard output or to
  405. a file.  The program reports its usage as follows.
  406.  
  407.   Usage: prsave [options] startaddress endaddress [filename]
  408.   Options:
  409.     -b bank Specify the memory bank (in hex)
  410.     -p port Specify the printer port (0 to 3)
  411.  
  412. There is not much to say about this program.  The -b and -p options are the
  413. same as with prload (section 2.1).  Typical usage of this command is
  414. something like
  415.  
  416.     prsave 400 7e8 screenshot
  417.  
  418. which saves the C64 or C128 text screen to a file "screenshot", which can be
  419. loaded back with prload.
  420.  
  421.  
  422. 2.3 prcart
  423.  
  424. Prcart loads and starts VIC-20 cartridges.  It takes its input either from
  425. the standard input, or from files that contain the 4kB or 8kB ROM images
  426. for $A000-$BFFF and $6000-$7FFF, or from Commodore-style program files
  427. with starting address $A000 or $6000.  Prcart patches the cartridge
  428. autostart code so that a RESET will restart the transfer daemon instead of
  429. restarting the game.  This is definitely a must for a VIC-20 owner.
  430.  
  431. You need expansion memory at BLK5 and BLK3 to use this program, plus the
  432. memory required for the prserver daemon.  I have a 32kB RAM cartridge.
  433. Also, note that some VIC-20 cartridges try to overwrite themselves, as a
  434. copy protection.  So, you need a switch on R/-W, or you must patch such
  435. cartridges, which usually isn't too difficult.
  436.  
  437.   prcart: Uploads a cartridge to the VIC-20.
  438.  
  439.   Usage: prcart [options] [filename.a000 [filename.6000]]
  440.   Options:
  441.         -j addr Jumps to the specified address after the transfers.
  442.                 Not useful with auto-start cartridges.
  443.         -a addr Specifies the restart address of the game.  Default=20000.
  444.                 Only useful with auto-start cartridges.
  445.         -p port Specify the printer port number (0 to 3).
  446.  
  447. The -p option is the same than with all prlink utilities, the printer port
  448. number.
  449.  
  450. The -a option specifies the game restart address.  If you want to restart
  451. the game after hitting RESET, you can restart it without transferring it
  452. again by issuing a SYS command.  You can use this option to change the SYS
  453. address.
  454.  
  455. The -j option, which lets you to jump to the specified address, is only
  456. useful with cartridges that do not normally start automatically.  The start
  457. address varies from cartridge to cartridge.
  458.  
  459. A typical prcart command line looks like
  460.  
  461.     prcart OMEGA_RACE.
  462.  
  463.  
  464. 2.4 File and disk transfer commands
  465.  
  466. The file and disk transfer commands implemented in prlink use standard
  467. KERNAL routines.  This means very slow speed, but it also guarantees maximum
  468. compatibility with all C= mass memory equipment.  For instance, the prdisk
  469. command can copy disks of any capacity up to 999000 sectors, which is 243
  470. megabytes.
  471.  
  472. Note that these transfer commands only work with disk drives or pseudo
  473. drives, like the REU ramdisk.  The commands might work with sequential files
  474. stored on tapes, but not with program files.  (This has not been tested.)
  475. Bad news for X1541 cable users: As you cannot use serial devices while the
  476. prlink daemon is running, you won't have much use for these commands.
  477.  
  478. The file and disk programs download 6502 programs to the C= side, a kind of
  479. loadable modules which implement the actual file and disk operations.  These
  480. commands can optionally use some environment variables to locate the
  481. loadable module files.  They use PRLINKDIR to locate the directory, and each
  482. transfer utility uses a variable named after the utility and the server type
  483. (e.g. when using a Commodore 64, PRLINK_PRRFILE64, PRLINK_PRWFILE64,
  484. PRLINK_PRDISK64) for the filename.  The server type numbers are as follows:
  485.  
  486.     number    server type
  487.     ------    -----------
  488.     201    Commodore PET series (should be 2001, but must fit in a byte)
  489.     20    Commodore VIC 20
  490.     64    Commodore 64
  491.     16    Commodore 264 series (16, 116 or plus/4)
  492.     128    Commodore 128
  493.  
  494. If the variables are undefined, respectively "prrfile.prg", "prwfile.prg"
  495. and "prdisk.prg" are used.  The directory and file name are concatenated
  496. directly so the PRLINKDIR should probably end in a slash "/" (or, on
  497. AmigaDOS in a colon ":" or on MS-DOS in a backslash "\").  Alternatively,
  498. the complete pathname can be specified with the -l command line option.
  499.  
  500. Even if you compile the prlink server to a different address, you won't need
  501. to recompile your prrfile, prwfile or prdisk binaries.  Prlink detects the
  502. server's starting address and patches these extension programs as
  503. appropriate.  This allows you to use servers with different starting
  504. addresses with the same extension programs.  Thanks to this, the prdisk,
  505. prrfile and prwfile binaries compiled for the C128 work also on the C64 and
  506. on the VIC-20.
  507.  
  508.  
  509. 2.4.1 prrfile
  510.  
  511. Prrfile reads a file from C= disk to local disk.  Its usage is as follows.
  512.  
  513.   Usage: prrfile [options] filename [local filename]
  514.   Options:
  515.     -d device    Specify the device number (0-15)
  516.     -l filename    Specify the filename of the client program
  517.     -p port Specify the printer port (0 to 3)
  518.     -s sec. addr.   Specify the secondary address (0-15)
  519.   The filename can start with a $, in which case it is
  520.   printed as a directory, unless a local name is given.
  521.   The remote filename is converted to PETSCII.
  522.   The default local file name has / characters converted to -.
  523.  
  524. Again, the -p option is the same than in all prlink commands.  The -d option
  525. lets you to specify the Commodore disk drive device number, instead of the
  526. default, which is 8.
  527.  
  528. With the -s 15 option you can send a command to the disk drive.  This case is
  529. special: if you send a command, no data is read.  If the command is empty,
  530. data (the disk status) is read, converted to ascii, and printed (by default
  531. to stdout).  Reading the disk status means that the command must be completed
  532. first - that is why this is normally not done.  A side effect of closing the
  533. error channel (which happens before opening it) is that all other files on
  534. the drive, and non-error messages such as "01,files scratched,00,00" and
  535. "73,cbm dos v2.6 1541,00,00" are forgotten by the drive.  Please keep this in
  536. mind.  To avoid this, execute a Basic CLR instruction before reading the
  537. error channel.
  538.  
  539. Prrfile can be used as simply as
  540.  
  541.     prrfile file_to_be_copied.
  542.  
  543. If you have different C= computers on your network, you will need to set
  544. some environment variables (Section 2.4), or to use the -l option to specify
  545. the prrfile module to load.
  546.  
  547.  
  548. 2.4.2 prwfile
  549.  
  550. Prwfile writes a file from local disk to C= disk.  Its usage is very similar
  551. to prrfile.
  552.  
  553.   prwfile: Writes a local file to a file on a remote computer.
  554.  
  555.   Usage: prwfile [options] filename [remote filename]
  556.   Options:
  557.     -d device    Specify the device number (0-15)
  558.     -l filename    Specify the filename of the client program
  559.     -p port Specify the printer port (0 to 3)
  560.     -s sec. addr.   Specify the secondary address (0-15)
  561.   The remote filename is converted to PETSCII.
  562.  
  563. Consult to Section 2.4.1 for documentation for the command line switches.
  564.  
  565.  
  566. 2.4.3 prdisk
  567.  
  568. Prdisk reads or writes whole C= disks to/from local files.  All media sizes
  569. are supported.  The only requirement is that the first track is 1 and the
  570. first sector on each track is 0.  Tracks and sectors increment up to 999.
  571.  
  572.   Usage: prdisk [options] [filename]
  573.   Options:
  574.     -d device    Specify the device number (0-15)
  575.     -r    Specify read operation (default)
  576.     -w    Specify write operation
  577.     -l filename    Specify the filename of the client program
  578.     -p port Specify the printer port (0 to 3)
  579.  
  580. By default, prdisk dumps a disk from device 8 to standard output.  If you
  581. specify a file name, the disk will be dumped to that file.  With the -w
  582. switch you can specify write operation, i.e. the specified file (or standard
  583. input) will be written to a disk in device 8 starting from track 1, sector
  584. 0.
  585.  
  586. The -d, -l and -p options work just like with prrfile and prwfile.
  587.  
  588.  
  589. 2.5 Miscellanous utilities
  590.  
  591. The prlink distribution package includes two utilities to be used with the
  592. Commodore 64, and a synchronous fastloader for the 1541 and 1571 and
  593. compatibles, which runs on the VIC-20, on the C64, on the Commodore 264
  594. Series and on the C128.  All utilities were written by Marko.
  595.  
  596.  
  597. 2.5.1 tod.a65
  598.  
  599. Tod.a65 measures the time spent in an interrupt in hours, minutes, seconds
  600. and tenth of seconds, as read from the Time of Day clock register.  It
  601. assumes that the power frequency is 50 Hz.  The times will be displayed on
  602. the screen, if they are at least two tenths of a second.
  603.  
  604. Tod.a65 was developed to measure prlink performance.  It also works on the
  605. Commodore 128.  Start it with SYS12288 after starting the prserver daemon,
  606. and see how much time a 64 kilobyte transfer ("prsave 0 0 file") will
  607. consume with your equipment.
  608.  
  609.  
  610. 2.5.2 playtune.a65
  611.  
  612. I have a bunch of Commodore 64 music files that I downloaded from
  613. ftp.funet.fi:/pub/cbm/c64/audio/vibrants.  These modules use a common
  614. format.  They must be initialized with a call to $1000, and the music will
  615. be played by calling $1003 once per picture frame.
  616.  
  617. As there are loads of these files, I didn't want to transfer them first to
  618. my C64, but I wanted to play them easily with a simple prload command.  So,
  619. I created a simple player.  Its disadvantage was caused by the prserver
  620. daemon: it disables itself, if you start a program with it.  So, I had to
  621. make the player restart the prserver daemon.
  622.  
  623. The player is very simple.  By default, it will compile to $c800, and it
  624. assumes that the prserver daemon starts at $cd00.
  625.  
  626. To use the player, you must have the prserver daemon started on your C64
  627. (Section 1.3).  Assumed that you have the player (playtune.prg) and Toccato
  628. (ftp.funet.fi:/pub/cbm/c64/audio/vibrants/dek/14/14toccat.dek) in the
  629. current directory.  The music will start playing on your C64 after issuing
  630. the following command:
  631.  
  632.     prload -j c800 playtune.prg 14toccat.dek
  633.  
  634. You could also do it in two parts:
  635.  
  636.     prload playtune.prg
  637.     prload -j c800 14toccat.dek
  638.  
  639. And if you want to change the tune, just type e.g.
  640.  
  641.     prload -j c800 14treasu.dek
  642.  
  643. You don't need to load the player each time.
  644.  
  645. Beware that there are some musics with different init and play addresses.
  646. If you keep hearing the same piece after loading a new tune, make sure that
  647. prload reports the new tune's start address to be $1000.
  648.  
  649.  
  650. 2.5.3 fastload.a65
  651.  
  652.  
  653. This routine has actually nothing to do with prlink, except that it uses a
  654. similar protocol as prlink.  This is a synchronous fastloader routine to be
  655. used with a 1541 or 1571 disk drive, also known as "IRQ loader".  Because the
  656. transfer routines are synchronous, the loader works on both PAL-G and NTSC-M
  657. systems, also in fast processor modes.
  658.  
  659. The loader uses the synchronous IEC bus protocol that is described in Section
  660. 6.5.  Everything is fully asynchronous, so the transfer won't be disturbed by
  661. any amount of interrupts on the computer.
  662.  
  663. The loader was modified from a disassembly listing that I got a long time ago.
  664. I assume that it was the loader of the G.I.Joe game, because it only compared
  665. the first two characters of the filenames.  I practically rewrote everything,
  666. only some label names remained.  I also left the two-character filename
  667. comparison there.
  668.  
  669. Using the loader is very simple.  Select the target system and compile the
  670. loader with DASM (e.g. "make TARGET=c64 fastload.prg").  You will need to
  671. initialize the disk drive with a single call to "init".  Note that the FA
  672. system variable, which holds the current (or last used) device number, must be
  673. properly set before calling the routine.  After the initializations, the drive
  674. will sit in a loop, waiting for the fastload command.  If the ATN signal gets
  675. asserted, the fastloader will quit to normal operation.  So, the drive does
  676. not prevent any normal bus operations; you just have to reinstall the routine
  677. if you want to use it again.  If there aren't any other activities on the bus,
  678. you can load several files with the fastloader without reinstalling it.
  679.  
  680. The constant LEDFLASH controls the drive LED flashing.  There are four
  681. options.  If LEDFLASH=0, the drive LED acts normally (e.g. it is lit
  682. constantly while a file is being loaded).  If LEDFLASH=1, the drive LED will
  683. glow on and off while the drive is waiting for a request.  From this glow
  684. you will recognize if the fast loader is active.  If LEDFLASH=2, the drive
  685. LED will be on while reading a sector, and off otherwise.  Setting LEDFLASH=3
  686. combines these two advanced options.
  687.  
  688. When the fastloader is installed, you can load program files by loading the
  689. first two filename characters to the X and Y registers and by calling the
  690. "irqload" routine.  The Carry flag will be set in return, if the file could
  691. not be loaded.
  692.  
  693. There is only one possible flaw in the loader.  If the computer gets
  694. interrupted right after it has sent the second character of the filename but
  695. before it has completed the handshake, and if the interruption lasts so long
  696. that the drive starts sending the first program byte (or an error code), the
  697. computer will remain in the loop, waiting for the handshake that occurred a
  698. long time ago.  This could be solved with a watchdog timer or something.  But
  699. actually this is not much of a problem, since the drive will read the disk
  700. directory before sending the status byte, which should last longer than any
  701. interruption on the computer side.
  702.  
  703. Interrupts are disabled on the drive while sending data.  This is mainly for
  704. improving the performance.  However, interrupts must be disabled when sending
  705. the last byte, right before returning to the main loop.  This prevents the
  706. deadlock situation on the drive side.  Note that the interrupts must be
  707. enabled while waiting for the file name, because the disk motor is controlled
  708. by the interrupt routine.  If interrupts are disabled, the disk will not stop
  709. spinning.
  710.  
  711. These deadlocks could have been avoided by using the protocol described in
  712. Section 6.5.2, but it would have made the loader bigger and slightly slower.
  713.  
  714.  
  715. 3. HARDWARE
  716.  
  717. Prlink requires a special cable that is connected to your PC's or your
  718. Amiga's parallel port (also known as the printer port or the Centronics
  719. port).  The cable's other end must be connected to your Commodore's user
  720. port, with the exception of the X1541 cable, which connects to the IEC bus
  721. (serial bus).
  722.  
  723. The PC64 cable is the cable used by the Personal C64 emulator written and
  724. marketed in Germany by Wolfgang Lorenz <100112.220@compuserve.com>.  It uses
  725. 4 independent data lines for both directions.  If you are using or are
  726. planning to use this emulator, then you are best off using this cable.
  727.  
  728. The prlink cable allows 8-bit data transfers from the PC to the C= side, and
  729. 4 bits from the C= to the PC.  It uses four bidirectional lines on the PC.
  730.  
  731. The software also supports the X1541 cable, a cable designed for connecting a
  732. Commodore disk drive to your PC.  It is the only option for Commodore 16
  733. users, because of the lack of a user port.  The transfer is slow, 1 bit at a
  734. time.  As the X1541 cable uses the serial bus for the transfers, the transfer
  735. daemon might get confused by any disk activities.  This means that you cannot
  736. use prrfile, prwfile or prdisk with this cable.
  737.  
  738. On the Amiga, there is only one cable that works with all protocols supported
  739. by the Amiga version.  Also, if you have built the cable for the TransNib
  740. software, prlink will work with it, although slower.
  741.  
  742. For compatibility reasons, the PC versions support the 64NET cable, which
  743. allows a pretty inefficient 4-bit/2-bit protocol.
  744.  
  745.  
  746. 3.1 Cable pinouts
  747.  
  748. Note that we disclaim any warranties, so you are using these instructions at
  749. your own risk.  Do not insert the plug to the user port the wrong way
  750. around, or you'll blow your printer port on the PC with the 9 volt signal as
  751. Marko did.
  752.  
  753. The 64NET cable pinout won't be listed, as the 64NET documentation claims
  754. that it is copyrighted.  Besides, including it would be a waste of space, as
  755. other cables allow much faster protocols.
  756.  
  757.  
  758. 3.1.1 The PC64 cable
  759.  
  760.          PC            C64      Comment
  761.  
  762.      GND    25   ------   A  GND      Ground
  763.      D7     9   ------>  B  FLAG      Handshake signal
  764.      ERROR    15  <------   C  PB0      Data from C= to PC
  765.      SEL    13  <------   D  PB1           "
  766.      PE    12  <------   E  PB2           "
  767.      ACK    10  <------   F  PB3           "
  768.      D0     2   ------>  H  PB4      Data from PC to C=
  769.      D1     3   ------>  J  PB5           "
  770.      D2     4   ------>  K  PB6           "
  771.      D3     5   ------>  L  PB7           "
  772.      BUSY    11  <------   M  PA2      Handshake signal
  773.  
  774.  
  775. 3.1.2 The prlink cable
  776.  
  777.          PC            C64      Comment
  778.  
  779.      GND    25   ------   A  GND      Ground
  780.      D3     5   ------>  B  FLAG      Handshake signal
  781.      STROBE  1  <------>  C  PB0      Bidirectional data lines
  782.      AUTO    14  <------>  D  PB1           "
  783.      INIT    16  <------>  E  PB2           "
  784.      SELECT 17  <------>  F  PB3           "
  785.      D4     6   ------>  H  PB4      Data from PC to C=
  786.      D5     7   ------>  J  PB5           "
  787.      D6     8   ------>  K  PB6           "
  788.      D7     9   ------>  L  PB7           "
  789.      BUSY    11  <------   M  PA2      Handshake signal
  790.  
  791.  
  792. 3.1.3 The pramiga cable
  793.  
  794.        Amiga           PET      Comment
  795.  
  796.      GND    22   ------   A  GND      Ground
  797.      POUT    12   ------>  B  CA1      Handshake signal (strobe/flag)
  798.      D0     2  <------>  C  PA0      Bidirectional data lines
  799.      D1     3  <------>  D  PA1           "
  800.      D2     4  <------>  E  PA2           "
  801.      D3     5  <------>  F  PA3           "
  802.      D4     6  <------>  H  PA4      Data from Amiga to PET
  803.      D5     7  <------>  J  PA5           "
  804.      D6     8  <------>  K  PA6           "
  805.      D7     9  <------>  L  PA7           "
  806.      BUSY    11  <------   M  CB2      Handshake signal (ack)
  807.  
  808. On the PET, Olaf chose to use CB2 even though that pin is normally
  809. connected to a speaker.  He did this because it makes the cable identical
  810. to the 64 and VIC cable, and allows you to use a single-sided connector.
  811. Make sure though that it does not connect the top and bottom fingers! Also
  812. you can hear nicely when the transfer is going on.
  813.  
  814. Note that the lower user port connections are named ABCDEFHJKMMN,
  815. skipping G and I.
  816.  
  817. On the Amiga 1000, pin 25 is not GND so Olaf picked 22 instead which
  818. should be GND on all Amiga models.  On the PC, all pins from 18 to 25
  819. should be GND.
  820.  
  821. The Amiga cable allows for two protocols: the prlink compatible
  822. 4-bit/8-bit transfer, and a full 8-bit transfer, the option prlink88.
  823. In addition, the Amiga software supports a third protocol, the one for
  824. the TransNib cable.  TransNib is an older transfer system for Amiga and
  825. C64.  Its cable has only 6 Centronics data bits connected:
  826.  
  827.   D0-3 <-> PA0-3:   data i/o
  828.   D6   <-- PA6:        handshake in (from C= to Amiga)
  829.   D7   --> PA7:        handshake out (from Amiga to C=)
  830.  
  831. The Amiga cable is downward compatible with the TransNib cable, so you
  832. can use it with the TransNib cable protocol, but of course it is slower.
  833.  
  834. If you need to make a cable there is no reason to not make the full
  835. pramiga cable; The transnib protocol is provided for people who made a
  836. cable for TransNib V1.00 Devised by Matt Francis
  837. (m.p.francis@newcastle.ac.uk).
  838.  
  839.  
  840. 3.1.4 The X1541 cable
  841.  
  842.       PC                   IEC bus    Comment
  843.  
  844.      GND    22   ------   2    GND      Ground
  845.      STROBE  1   ------>  3    ATN    not used
  846.      AUTOFD 14  <------>  4    CLK    Bidirectional data/handshake line
  847.      SELECT 17  <------   5    DATA   Bidirectional data/handshake line
  848.  
  849. As you may note, not all lines of the original X1541 cable are
  850. required.  The loop from D0 (pin 2) to ERROR (pin 15) is missing, as
  851. well as the connection from INIT (pin 16) to RESET (pin 6).  The ATN
  852. line is not required either, but it is required by other transfer
  853. programs that use this cable.  Prlink will work with these additions
  854. installed, so you don't need to modify your existing X1541 cable.
  855.  
  856. Prlink also supports the Disk64e cable, which is quite obsolete.  The Disk64e
  857. code replaces the X1541 code if you define the preprocessor name DISK64E when
  858. compiling the module prtrans1.c.  Marko accidentally built the Disk64e cable
  859. first; that is why it is supported.
  860.  
  861.  
  862. 3.2. Transfer trouble
  863.  
  864. For some reason Olaf had weird problems with his 64 when using the prlink
  865. protocol.  He might be the only one suffering from this, but if you too get
  866. hung transfers when transferring from the 64 to the Amiga, try to run the
  867. transnib protocol over the prlink cable.  It is slower but generally causes
  868. less hung transfers.
  869.  
  870. To get more technical: When the data lines are changed by the 64, the
  871. handshake line from the 64 sometimes starts bouncing, causing the Amiga side
  872. to get so confused that the computers get too much out of sync.  Olaf
  873. doesn't know if it's a problem with his cable (perhaps it is a bit long),
  874. his 64, or his Amiga, or any of those in general.
  875.  
  876. Because of this, we have included bounce detection in the following cases:
  877.  
  878. - prlink and prlink88, Amiga.  The bounce on the handshake line to the Amiga
  879. (BUSY) happens with both Olafs PET and 64, but more with the 64.  When
  880. reading its state, we require its readout to be stable for 3 consecutive
  881. accesses.  Since the CIAs in the Amiga run at 0.714 MHz, an access takes
  882. about 1.4 microseconds.
  883.  
  884. - prlink and prlink88, 64. The edge-sensitive handshake line to the 64 (FLAG)
  885. is apparently rather sensitive.  When a false trigger occurs this fact is
  886. latched in the interrupt bit.  By reading (and thereby clearing) the
  887. Interrupt Flag Register at the latest possible moment before the next
  888. handshake could come in, phantom handshakes caused by bounce seem to be
  889. significantly reduced.
  890.  
  891. If you wish to turn off the bounce detection, you can do this by changing
  892. some flags.  For the 6502 side, edit the file prtrans.inc and change the
  893. definition of "debounce" to 0.  For the Amiga side, change DEBOUNCE and
  894. DEBOUNCE2 to 0.  Next you need to recompile and test if the transfer still
  895. works correctly.
  896.  
  897. If the transfer hangs, you can stop the server on the Commodore side with
  898. STOP & Restore.  The AmigaDOS or Linux client can be stopped with normal
  899. means, i.e. Ctrl-D on the Amiga, and Ctrl-C on Linux.  The MS-DOS clients
  900. can be stopped by pressing Esc.
  901.  
  902.  
  903. 4. COMPILATION
  904.  
  905. To compile the binaries for AmigaDOS or Linux, you need GNU Make, GNU C
  906. compiler (tested with 2.5.8 and 2.6.2, any version should do) and related
  907. tools.  Also, you need the DASM port made by Olaf Seibert.  It can be
  908. downloaded from ftp.funet.fi:/pub/cbm/programming/dasm.tar.gz.
  909.  
  910. The MS-DOS executables can be compiled with Microsoft C/C++ v8.00, which is
  911. part of Microsoft Visual C++ v1.5.
  912.  
  913. The software supports several different cables.  The transfer routines for
  914. the different cables are in prtrans2.c, prtrans4.c, prtrans8.c and
  915. pramiga.c.  You will have to edit the Makefile to specify which cable
  916. (CABLEOBJ) and default printer port to use.  The latter one is not required
  917. in the Amiga version.  The Amiga version also allows the -DPRLINK88 option,
  918. which uses full 8-bit transfer, and -DTRANSNIB option for compatibility with
  919. the TransNib cable.
  920.  
  921.  
  922. 4.1 Automatic compilation
  923.  
  924. For Amiga and Linux, we have created useful MakeAll scripts in the src
  925. directory.  The Linux version is MakeAll.sh.  It makes all C= executables for
  926. all supported cables and memory expansions, and the Linux prmain executable
  927. for all those cables.  The Amiga version of this script, MakeAll.rexx, makes
  928. all C= binaries and the Amiga executable in similar manner.  Assuming that
  929. the source tree is prlink-0.9.5b/src, the binary tree will be
  930. prlink-0.9.5b/bin.  The binary distribution tree is as follows:
  931.  
  932.   COPYING        The GNU General Public License.
  933.   README        this file
  934.   README.Amiga        Additional information for the Amiga.
  935.   Start.Amiga        Startup definitions for the Amiga.
  936.   Start.bash        Startup definitions for Linux (requires bash).
  937.   Start.tcsh        Startup definitions for Linux (requires tcsh).
  938.   loader.bas        A BASIC listing that you can type in to transfer the
  939.             prserver binaries, using the prlink or PC64 cable.
  940.   startdos.bat        Startup definitions for MS-DOS.
  941.   
  942.   bin/pet3001/        Binaries for the PET3001 series
  943.     prlink/        prserver daemons for the PRLINK protocol
  944.     prlink88/        prserver daemons for the PRLINK88 protocol (Amiga only)
  945.     transnib/        prserver daemons for the TransNib cable (Amiga only)
  946.     pc64/        prserver daemons for the PC64 cable (PC only)
  947.     c64net/        prserver daemons for the 64NET cable (PC only)
  948.       prserver.prg    a basic daemon supporting no special memory expansions
  949.  
  950.     prdisk.prg        prdisk loadable module
  951.     prrfile.prg        prrfile loadable module
  952.     prwfile.prg        prwfile loadable module
  953.  
  954.   bin/pet4001/        Binaries for the PET4001 series
  955.     ...            (contents as above)
  956.   bin/vic20/        Binaries for the Commodore VIC-20
  957.     ...            (contents as above, plus)
  958.     iec/        prserver daemons for the X1541 cable
  959.   bin/c64/        Binaries for the Commodore 64
  960.     ...            (contents as above, plus)
  961.     prlink/        prserver daemons for the PRLINK protocol
  962.     prlink88/        prserver daemons for the PRLINK88 protocol (Amiga only)
  963.     transnib/        prserver daemons for the TransNib cable (Amiga only)
  964.     pc64/        prserver daemons for the PC64 cable (PC only)
  965.     c64net/        prserver daemons for the 64NET cable (PC only)
  966.     iec/        prserver daemons for the X1541 cable
  967.       prpia.prg        a daemon version supporting the PIA expansion
  968.       prreu.prg        a daemon version supporting the Commodore REU
  969.       prpiareu.prg    a daemon version supporting both the PIA and the REU
  970.   bin/c128/        Binaries for the Commodore 128
  971.     ...            (contents as above, plus)
  972.     bootsect.prg    a boot sector for automatically starting one of the
  973.             prserver daemons on the C128
  974.  
  975.   bin/c16/        Binaries for the Commodore 16, 116 and plus/4
  976.     iec/        prserver daemons for the X1541 cable
  977.       prserver.prg    a basic daemon
  978.  
  979.   bin/linux/        Linux prmain executable (in case of MakeAll.sh)
  980.     prmain        all clients for all cables
  981.  
  982.   bin/amiga/        Amiga prmain executable (in case of MakeAll.rexx)
  983.     prmain        all clients for all cables
  984.  
  985.   bin/msdos/        MS-DOS prmain executable (in the MS-DOS distribution)
  986.     prmain.exe        all clients for all cables
  987.  
  988.  
  989. 4.2 Manual compilation
  990.  
  991. If you are compiling the binaries manually, i.e. you want something special
  992. that cannot be achieved with the MakeAll scripts, you must run "make" in the
  993. "src" directory yourself.
  994.  
  995. On MS-DOS systems, manual compilation is the only alternative.  The command
  996. is "NMAKE -F MAKEFILE.DOS".  MAKEFILE.DOS is designed for Microsoft NMAKE
  997. and Microsoft C/C++ v8.00, which are included with Microsoft Visual C++ for
  998. Windows v1.5.  If you are going to use some other compiler, note that you
  999. must use large memory model (multiple data segments) and that extern
  1000. variables must be assumed to be far.
  1001.  
  1002. First you have to edit src/Makefile, or SRC\MAKEFILE.DOS in MS-DOS.  The
  1003. definitions for the CLIENT, TARGET, RAMEXP and CABLE variables must be
  1004. checked.  You have the following options that affect the Commodore side:
  1005.  
  1006.   definition    options
  1007.   ----------    -------
  1008.   TARGET    target system, i.e. vic20, c64, c128 etc.
  1009.  
  1010.   RAMEXP    none    no memory expansion installed
  1011.         piaexp    the PIA expansion for the C64 and the C128
  1012.             (ftp.funet.fi:/pub/cbm/documents/{256kB,1028})
  1013.         reuexp    Commodore RAM Expansion Unit
  1014.         pet96    PET 8096/8296 expansion (not yet implemented)
  1015.  
  1016.   CABLE        prlink     the default 8-bit/4-bit cable
  1017.         pc64     the 4-bit/4-bit cable used by the PC64 emulator
  1018.         c64net     the 4-bit/2-bit cable used by 64NET
  1019.         prlink88 fully 8-bit transfers with the Amiga cable
  1020.         transnib TransNib compatible alternative for Amiga
  1021.  
  1022. The client (Amiga or PC) options are as follows:
  1023.  
  1024.   definition    options
  1025.   ----------    -------
  1026.   CLIENT    client system, i.e. AmigaDOS or Linux.
  1027.         Not used in MAKEFILE.DOS (MS-DOS version).
  1028.  
  1029. The following variables are undefined by default.  When defined, they
  1030. have following effects:
  1031.  
  1032.   definition    effect
  1033.   ----------    ------
  1034.   DEBUG        Generate code for the GNU debugger gdb. (Makefile only)
  1035.   NO_ASM    Disable inline assembler.
  1036.   FIXED        Generate separate executables for all clients.
  1037.  
  1038. The FIXED option is probably most useless, unless you are going to run
  1039. the prlink clients on a very small system.  By default, all functions
  1040. and transfer protocols will be integrated into one executable.  When
  1041. you use the FIXED option, there will be compiled separate executables
  1042. for all functions, i.e. prload, prsave and so on.  Only one transfer
  1043. protocol will be supported.  It is specified by the CABLE setting.
  1044.  
  1045. You don't necessarily actually need to modify the Makefile.  The
  1046. variables can also be specified on the command line, i.e.:
  1047.  
  1048.     make DEBUG=1 FIXED=1 CABLE=prlink CLIENT=Linux clean clients
  1049.  
  1050. or
  1051.  
  1052.     nmake -f makefile.dos DEBUG=1 FIXED=1 CABLE=prlink clean clients
  1053.  
  1054. The following explicitly defined build targets are available:
  1055.  
  1056.   target    meaning
  1057.   ------    -------
  1058.   all        build "clients" and "prprgs"
  1059.   clients    build all clients, i.e. prload, prsave and so on
  1060.   prprgs    build all Commodore side utilities for the selected config
  1061.   prmain        build the client executable (in case FIXED is not specified)
  1062.   prmain.exe    ditto, in case of MS-DOS distribution
  1063.   clean        remove object files
  1064.   reallyclean    remove object and executable files
  1065.  
  1066. Also, you may need to change the following definitions in prserver.asm, if
  1067. using the PIA and/or REU expansions:
  1068.  
  1069.   pia        the PIA base address, e.g. $dff0
  1070.   reu        the REU base address, e.g. $df00
  1071.   actionreuplay    If you are using Action Replay and the REU
  1072.         simultaneously, set this to 1.  You can connect them
  1073.         in parallel manner to the cartridge port if you add a
  1074.         switch to the REU that disables the -I/O2 signal when
  1075.         R/-W is high.  Effectively, you can do this with the
  1076.         following components:
  1077.  
  1078.                     /o-------+
  1079.         -I/O2 ----o/         |
  1080.         (from C64)   o->|----+--- -I/O2 (to REU)
  1081.                              |
  1082.         R/-W  --------->|----+
  1083.                      1N4148  |
  1084.                      diodes  <
  1085.                              > 4k7
  1086.                              < resistor
  1087.                              >
  1088.                              |
  1089.                            --+--
  1090.  
  1091.         If you also modify Action Replay so that its -I/O2 gets
  1092.         disabled when R/-W is low, you won't need the
  1093.         actionreuplay option.  But this modification cannot be
  1094.         implemented with diodes and resistors.  Instead, you would
  1095.         need an IC (quad NAND or something), which may be difficult
  1096.         to fit in the Action Replay case.
  1097.  
  1098.         When the switch is in its upper position, the REU will
  1099.         operate as previously, i.e. it won't work with the
  1100.         Action Replay cartridge.  When it is in the lower position,
  1101.         the Action Replay cartridge will work, but you will most
  1102.         probably have problems with any software that uses the REU
  1103.         (except prlink).  Thus, whenever you want to use anything
  1104.         that supports the REU, you must disable the Action Replay
  1105.         cartridge and then move the switch to the upper position.
  1106.  
  1107.  
  1108. 5. PERFORMANCE OVERVIEW
  1109.  
  1110. For maximum performance, you should use the native prlink cable.  But as you
  1111. can see from these results, the PC64 cable is not much slower.
  1112.  
  1113. Client: 486DX2/66 with 128kB cache
  1114. OS:     Linux, no processes running on the background
  1115.         MS-DOS (with and without EMM386)
  1116. Server: Commodore 128D with 1 MB internal memory and 1 MB REU
  1117. Data block: 64 kilobytes
  1118.  
  1119.  
  1120. PC64 cable:
  1121.  
  1122. prsave prload server
  1123. ------ ------ ------
  1124.  3.7s   4.0s  c128 (pia)
  1125.  4.8s   5.3s  c128 (stock)
  1126.  3.7s   3.9s  c128 in c64 mode (pia)
  1127.  4.1s   4.0s  c128 in c64 mode (stock)
  1128.  7.1s   7.5s  c64 (pia)
  1129.  7.8s   7.6s  c64 (stock)
  1130.  
  1131. prlink cable (bounce code installed):
  1132.  
  1133. prsave prload server
  1134. ------ ------ ------
  1135.  4.7s   2.6s  c128 (pia)
  1136.  5.8s   3.9s  c128 (stock)
  1137.  4.7s   2.6s  c128 in c64 mode (pia)
  1138.  5.1s   2.3s  c128 in c64 mode (stock)
  1139.  8.0s   5.1s  c64 (pia)
  1140.  8.8s   5.1s  c64 (stock)
  1141.  
  1142. prlink cable (no bounce code):
  1143.  
  1144. prsave prload server
  1145. ------ ------ ------
  1146.  4.2s   2.5s  c128 (pia)
  1147.  5.5s   3.8s  c128 (stock)
  1148.  4.2s   2.5s  c128 in c64 mode (pia)
  1149.  4.8s   2.5s  c128 in c64 mode (stock)
  1150.  7.5s   4.8s  c64 (pia)
  1151.  8.2s   4.9s  c64 (stock)
  1152.  
  1153. These timings were measured on the C128D, using a program that measures the
  1154. time spent in interrupts by reading the TOD clock.  The program's source
  1155. code is in src/tod.a65.  Processor time spent on the PC is a bit more,
  1156. because of the initializations, and because the transfer won't start until a
  1157. timer interrupt occurs on the Commodore end.
  1158.  
  1159. The prlink cable with the 4-bit/8-bit protocol is a bit slower with prsave
  1160. than the PC64 cable.  This is due to the handshaking performed with
  1161. exclusive-or instead of constant values.  But if you're using Amiga, you can
  1162. enable full 8-bit transfer to get rid of this problem.
  1163.  
  1164. As you can see from the figures, the stock C128 is faster in C64 mode,
  1165. because the memory banking is simpler.  Surprisingly (or maybe not), the
  1166. transfer rate did not change under MS-DOS, even though Linux is a
  1167. multitasking operating system.
  1168.  
  1169.  
  1170. 6. PROTOCOLS
  1171.  
  1172. The prlink package uses a wide variety of transfer protocols, one for each
  1173. supported cable type.  The protocols are the most important part of the
  1174. software, so they must be thoroughly described.
  1175.  
  1176. Because the software is strictly non-blocking, i.e. you do not have to run a
  1177. program on either end that would just sit in a loop, busy-waiting for
  1178. transfer events, and because the client software may run in an pre-emptive
  1179. multitasking environment, the transfer protocols must be fully synchronous.
  1180.  
  1181. On the server (Commodore) side, all protocols are implemented in the file
  1182. prtrans.inc.  The transfer routines for PC clients are implemented in
  1183. the files prtrans[1248].c, one file for each protocol.  The routines for
  1184. the Amiga are currently in one single file, pramiga.c.
  1185.  
  1186. For clarity, all signal names in the following description are from the
  1187. Commodore 64 user port.  See Section 3.1 (Cable pinouts) for a reference of
  1188. the actual pinouts and corresponding PC or Amiga names.  Note that -FLAG is
  1189. an edge-sensitive input on the C64 that only detects a high-to-low
  1190. transition.  The line must be held low long enough for the transition to be
  1191. detected.  All other lines are "normal", level-sensitive, and on the server
  1192. (Commodore) side, a low voltage level is used to present a '0' bit, while a
  1193. high voltage level presents a '1' bit.
  1194.  
  1195.  
  1196. 6.1 The PC64 cable (PC only)
  1197.  
  1198. The PC64 cable allows for 4-bit transfers in both directions.  It has eight
  1199. data lines, four for both directions, and two handshake signals, one for the
  1200. sending and one for the receiving end.  It is quite simple and should work
  1201. even with the cheapest parallel ports.
  1202.  
  1203.  
  1204. 6.1.1 Sending a byte to the server
  1205.  
  1206. PC:  put the data bits 0..3 on PB4..PB7 and drop -FLAG
  1207. C64: wait for the falling edge of -FLAG
  1208. C64: read the data bits, drop PA2
  1209. PC:  wait for low level on PA2
  1210. PC:  raise -FLAG
  1211. PC:  put the data bits 4..7 on PB4..PB7 and drop -FLAG
  1212. C64: wait for the falling edge of -FLAG
  1213. C64: read the data bits, raise PA2
  1214. PC:  wait for high level on PA2
  1215. PC:  raise -FLAG
  1216.  
  1217.  
  1218. 6.1.2 Receiving a byte from the server
  1219.  
  1220. PC:  drop -FLAG
  1221. C64: wait for the falling edge of -FLAG
  1222. C64: put the data bits 0..3 on PB0..PB3 and drop PA2
  1223. PC:  wait for low level on PA2
  1224. PC:  raise -FLAG, read the data bits
  1225. PC:  drop -FLAG
  1226. C64: wait for the falling edge of -FLAG
  1227. C64: put the data bits 4..7 on PB0..PB3 and raise PA2
  1228. PC:  wait for high level on PA2
  1229. PC:  raise -FLAG, read the data bits
  1230.  
  1231.  
  1232. 6.1.3 Changing the data direction
  1233.  
  1234. The data direction can be changed without any special measures.
  1235.  
  1236.  
  1237. 6.2 The prlink cable, 4-bit/8-bit protocol
  1238.  
  1239. The prlink cable utilizes four lines on the client side that should be
  1240. bidirectional on all PC printer ports.  On the Amiga printer ports, they
  1241. definitely are bidirectional.  These lines are the only data lines from the
  1242. server to the client.  For transfers from the client to the server, the
  1243. protocol utilizes also four output lines, which allows 8-bit transfers.
  1244.  
  1245. 6.2.1 Sending a byte to the server
  1246.  
  1247. PC:  put the data bits 0..7 on PB0..PB7 and drop -FLAG
  1248. C64: wait for the falling edge of -FLAG
  1249. C64: read the data bits, change the state of PA2
  1250. PC:  wait for PA2 to change its state
  1251. PC:  raise -FLAG
  1252.  
  1253.  
  1254. 6.2.2 Receiving a byte from the server
  1255.  
  1256. PC:  drop -FLAG
  1257. C64: wait for the falling edge of -FLAG
  1258. C64: put the data bits 0..3 on PB0..PB3 and toggle PA2
  1259. PC:  wait for PA2 to change its state
  1260. PC:  raise -FLAG, read the data bits
  1261. PC:  drop -FLAG
  1262. C64: wait for the falling edge of -FLAG
  1263. C64: put the data bits 4..7 on PB0..PB3 and toggle PA2
  1264. PC:  wait for PA2 to change its state
  1265. PC:  raise -FLAG, read the data bits
  1266.  
  1267.  
  1268. 6.2.3 Changing the data direction
  1269.  
  1270. As the protocol uses bidirectional data lines, the data direction of these
  1271. lines must be reconfigured when changing the data direction.  This is managed
  1272. on the server side.  The client side can always call input and output
  1273. routines without any special measures.
  1274.  
  1275. When the data flow direction changes on the server, the server first waits
  1276. for the falling edge of -FLAG, then reprograms the lines' data direction and
  1277. finally transfers the byte in normal manner.
  1278.  
  1279.  
  1280. 6.3 The prlink cable, true 8-bit protocol (Amiga only)
  1281.  
  1282. This is the fastest protocol that the prlink package supports.  It uses two
  1283. handshake signals and eight data lines.
  1284.  
  1285.  
  1286. 6.3.1 Sending a byte to the server
  1287.  
  1288. Ami: put the data bits 0..7 on PB0..PB7 and drop -FLAG
  1289. C64: wait for the falling edge of -FLAG
  1290. C64: read the data bits, change the state of PA2
  1291. Ami: wait for PA2 to change its state
  1292. Ami: raise -FLAG
  1293.  
  1294.  
  1295. 6.3.2 Receiving a byte from the server
  1296.  
  1297. Ami: drop -FLAG
  1298. C64: wait for the falling edge of -FLAG
  1299. C64: put the data bits 0..7 on PB0..PB7 and toggle PA2
  1300. Ami: wait for PA2 to change its state
  1301. Ami: raise -FLAG, read the data bits
  1302.  
  1303.  
  1304. 6.3.3 Changing the data direction
  1305.  
  1306. As the protocol uses bidirectional data lines, the data direction of these
  1307. lines must be reconfigured when changing the data direction.  This is managed
  1308. on the server side.  The client side can always call input and output
  1309. routines without any special measures.
  1310.  
  1311. When the data flow direction changes on the server, the server first waits
  1312. for the falling edge of -FLAG, then reprograms the lines' data direction and
  1313. finally transfers the byte in normal manner.
  1314.  
  1315.  
  1316. 6.4 The TransNib cable (Amiga only)
  1317.  
  1318. The TransNib cable uses four bidirectional data lines, PB0..PB3, and two
  1319. handshaking lines, PB6 and PB7.  The protocol is quite inefficient, and it is
  1320. not fully asynchronous, but it is included for backward compatibility anyway.
  1321.  
  1322.  
  1323. 6.4.1 Sending a byte to the server
  1324.  
  1325. Ami: put the data bits 4..7 on PB0..PB3 and drop PB7
  1326. C64: wait for low level on PB7
  1327. C64: read the data bits and drop PB6
  1328. Ami: wait for low level on PB6
  1329. Ami: raise PB7
  1330. C64: wait for high level on PB7
  1331. C64: raise PB6
  1332. Ami: wait for high level on PB6
  1333. Ami: put the data bits 0..3 on PB0..PB3 and drop PB7
  1334. C64: wait for low level on PB7
  1335. C64: read the data bits and drop PB6
  1336. Ami: wait for low level on PB6
  1337. Ami: raise PB7
  1338. C64: wait for high level on PB7
  1339. C64: raise PB6
  1340. Ami: wait for high level on PB6
  1341.  
  1342.  
  1343. 6.4.2 Receiving a byte from the server
  1344.  
  1345. C64: put the data bits 4..7 on PB0..PB3 and drop PB6
  1346. Ami: wait for low level on PB6
  1347. Ami: read the data bits and drop PB7
  1348. C64: wait for low level on PB7
  1349. C64: raise PB6
  1350. Ami: wait for high level on PB6
  1351. Ami: raise PB7
  1352. C64: put the data bits 0..3 on PB0..PB3 and drop PB6
  1353. Ami: wait for low level on PB6
  1354. Ami: read the data bits and drop PB7
  1355. C64: wait for low level on PB7
  1356. C64: raise PB6
  1357. Ami: wait for high level on PB6
  1358. Ami: raise PB7
  1359.  
  1360.  
  1361. 6.4.3 Changing the data direction
  1362.  
  1363. As the protocol uses bidirectional data lines, the data direction of these
  1364. lines must be reconfigured when changing the data direction.  This is managed
  1365. on the server side.  The client side can always call input and output
  1366. routines without any special measures.
  1367.  
  1368. When the data flow direction changes on the server, the server first waits
  1369. for the falling edge of -FLAG, then reprograms the lines' data direction and
  1370. finally transfers the byte in normal manner.
  1371.  
  1372.  
  1373. 6.5 The IEC bus cable
  1374.  
  1375. The IEC bus has three wires that could be used for data transfers: CLK, DATA
  1376. and ATN.  Unfortunately, the ATN line is a bus propagation line, so it cannot
  1377. be used if there are other devices connected to the bus.  For this reason,
  1378. prlink's IEC bus protocol has been realized with only two bidirectional
  1379. lines: CLK and DATA.  You might wonder how this is possible, asynchronous
  1380. transfers with only two lines.  There are the two required handshake lines,
  1381. but where is the data line?
  1382.  
  1383. You can combine the handshake and data lines.  If you want to send a '0' bit,
  1384. you will pull the DATA line low, and if you want to send a '1', you will pull
  1385. CLK low.  The receiving end will then acknowledge by pulling the other line
  1386. low, and the sender replies to this by raising his line.  Finally, the
  1387. recipient will raise his handshake line, and the bus is ready for the next
  1388. bit being transferred.
  1389.  
  1390. This protocol has one problem (aside the speed, or better the lack of it):
  1391. Changing the data flow's direction.  In order to make it fully asynchronous,
  1392. special tricks must be applied.  Marko's IRQ loader, a fastloader that works
  1393. with all sorts of interrupts enabled (Section 2.5.3), uses a quick and dirty
  1394. method, to keep the code short.  This cannot be done in prlink, because the
  1395. client is often much faster than the server, but it can be much slower as well,
  1396. as it may run in a heavily loaded pre-emptive multitasking environment.  So,
  1397. prlink's IEC protocol must change the data direction fully asynchronously.
  1398.  
  1399.  
  1400. 6.5.1 Transferring a bit
  1401.  
  1402. Since the protocol is symmetrical, and since this protocol transfers single
  1403. bits, the description can be simplified.  In the following description, "snd"
  1404. denotes the sender and "rcv" the receiver.  This cycle is repeated 8 times
  1405. for a byte to be transmitted.  The LSB (bit 0) will be transferred first.
  1406.  
  1407. snd: drop DATA if sending a '0' bit; drop CLK if sending a '1' bit
  1408. rcv: wait for low level on DATA or CLK
  1409. rcv: read the data
  1410. rcv: drop the line that was high
  1411. snd: wait for low level on DATA and CLK
  1412. snd: raise DATA and CLK
  1413. * Note: The line held low by rcv will remain low.
  1414. rcv: wait for high level on DATA or CLK
  1415. rcv: raise DATA and CLK
  1416. snd: wait for high level on DATA and CLK
  1417.  
  1418.  
  1419. 6.5.2 Changing the data direction
  1420.  
  1421. Switching from sending to receiving does not require any modifications to the
  1422. bit transfer protocol, because the sending end will finish only after the
  1423. receiving end's acknowledgement.  But the other end must switch from receiving
  1424. to sending, and this is a problem.
  1425.  
  1426. Let's assume that there isn't be any special handling for changing the data
  1427. direction.  If the end that switches from receiving to sending is much faster
  1428. than the other end, it may do the switching too fast.  Let's see what happens.
  1429. The last bit before the switch is being transferred.  Everything goes fine
  1430. until the receiver raises DATA and CLK.  After that, the receiver does not
  1431. wait for anything, and it could start sending data, dropping the DATA or CLK
  1432. line.  If this happens fast enough, or if the former sender gets interrupted,
  1433. the former sender will never see a high voltage level on DATA and CLK.  So, it
  1434. will sit there, waiting for the former receiver's acknowledgement, which
  1435. already was on the bus.
  1436.  
  1437.  
  1438. 6.5.2.1 The quick and dirty solution
  1439.  
  1440. The easy and wrong way to fix this problem is to wait long enough before
  1441. sending the first data byte after the direction change, or by sending the last
  1442. byte before the direction change without interruption.  This was done in the
  1443. IRQ loader (Section 2.5.3), and it works, because the disk drive and the
  1444. computer run at almost the same speed.
  1445.  
  1446.  
  1447. 6.5.2.2 The correct solution
  1448.  
  1449. The correct way to solve the problem is using special handshaking, like below.
  1450. The name "rs" refers to the end that used to receive and will send after the
  1451. direction change, and the name "sr" refers to the former sender that will
  1452. start receiving the data.
  1453.  
  1454. rs: drop CLK and DATA
  1455. rs: raise CLK and DATA
  1456. rs: repeat the previous 2 steps until there is low level on CLK
  1457. rs: drop CLK
  1458. rs: wait for low level on DATA
  1459. rs: raise CLK
  1460. rs: wait for high level on DATA
  1461.  
  1462. sr: wait for low level on CLK and DATA
  1463. sr: drop CLK
  1464. sr: raise CLK
  1465. sr: repeat the previous 2 steps until CLK==low and DATA==high
  1466. sr: drop DATA
  1467. sr: wait for high level on CLK
  1468. sr: raise DATA
  1469.  
  1470. This handshaking relies on wired-and open-collector logic and on the fact that
  1471. CLK and DATA can be set simultaneously, because they are located in the same
  1472. peripheral register.  It also requires that the receiver and the sender must
  1473. not run at the exactly same speed.  Because the CLK and DATA lines are
  1474. switched low simultaneously by the "rs" end, the "sr" end can distinquish it
  1475. from a sent data bit.  Even if the "sr" end would be interrupted for long time
  1476. after it has risen CLK but before it has read the state of CLK and DATA, the
  1477. handshaking will work properly.
  1478.  
  1479. This handshaking is implemented on the client and on the server in the
  1480. functions send_switch and receive_switch.  As you see, the handshaking is
  1481. rather complicated.  We wanted to keep the initiative by the sender, so that
  1482. the bus remains in idle state (CLK and DATA high), when nothing is being
  1483. transferred.  With some extra logic, this would allow the usage of the serial
  1484. bus while the prserver daemon is running, when there are no requests from the
  1485. PC side.  Below is a simpler protocol where the new receiver will have the
  1486. handshaking initiative.
  1487.  
  1488. rs: wait for low level on CLK
  1489. rs: drop CLK and DATA
  1490. rs: raise CLK and DATA
  1491. rs: repeat the previous 2 steps until there is high level on DATA
  1492.  
  1493. sr: drop CLK
  1494. sr: wait for low level on DATA
  1495. sr: raise CLK
  1496. sr: wait for high level on CLK or DATA (or both)
  1497.  
  1498.  
  1499. 6.6 The 64NET cable (PC only)
  1500.  
  1501. This proprietary cable is included for historical reasons.  I developed my
  1502. first transfer routine for this cable, and as I saw how inefficient it was,
  1503. I decided to build a better cable.
  1504.  
  1505. The 64NET cable has four data lines from client (PC) to server (Commodore),
  1506. PB4..PB7, and two data lines from server to client, PB0 and PB1.  It has two
  1507. handshaking lines, PB2 and PB3.  Like the PC64 cable, it should work with any
  1508. parallel port.  As you see, the lines chosen are very badly on the server
  1509. side, so this cable only allows a very inefficient protocol.
  1510.  
  1511.  
  1512. 6.6.1 Sending a byte to the server
  1513.  
  1514. PC:  put the data bits 4..7 on PB4..PB7 and raise PB3
  1515. C64: wait for high level on PB3
  1516. C64: read the data bits, drop PB2
  1517. PC:  wait for low level on PB2
  1518. PC:  put the data bits 0..3 on PB4..PB7 and drop PB3
  1519. C64: wait for low level on PB3
  1520. C64: read the data bits, raise PB2
  1521. PC:  wait for high level on PB2
  1522.  
  1523.  
  1524. 6.6.2 Receiving a byte from the server
  1525.  
  1526. PC:  raise PB4..PB7, drop PB3
  1527. C64: wait for high level on PB4..PB7 and low level on PB3
  1528. C64: drop PB2
  1529. PC:  wait for low level on PB2
  1530. PC:  drop PB3..PB7
  1531. C64: wait for low level on PB3..PB7
  1532. C64: put the data bits 0 and 1 on PB0 and PB1 and raise PB2
  1533. PC:  wait for high level on PB2
  1534. PC:  read the data bits and raise PB3
  1535. C64: wait for high level on PB3
  1536. C64: put the data bits 2 and 3 on PB0 and PB1 and drop PB2
  1537. PC:  wait for low level on PB2
  1538. PC:  read the data bits and drop PB3
  1539. C64: wait for low level on PB3
  1540. C64: put the data bits 4 and 5 on PB0 and PB1 and raise PB2
  1541. PC:  wait for high level on PB2
  1542. PC:  read the data bits and raise PB3
  1543. C64: wait for high level on PB3
  1544. C64: put the data bits 6 and 7 on PB0 and PB1 and drop PB2
  1545. PC:  wait for low level on PB2
  1546. PC:  read the data bits and drop PB3
  1547. C64: wait for low level on PB3
  1548. C64: raise PB2
  1549. PC:  wait for high level on PB2
  1550.  
  1551. 6.6.3 Changing the data direction
  1552.  
  1553. The data direction can be changed without any special measures.
  1554.  
  1555.  
  1556.  
  1557. 7. CREDITS
  1558.  
  1559. Prlink was originally programmed for Linux and C64/C128/VIC-20 by Marko
  1560. Mäkelä.  Olaf Seibert joined the project and ported prlink to Amiga and the
  1561. PET series.  Since the original release, prlink has been ported to MS-DOS and
  1562. to the Commodore 16, and the program structure has been greatly improved.
  1563.  
  1564. I would like to express my thanks to all transfer program writers who gave me
  1565. the inspiration to create prlink, whose main goal is to be compatible with
  1566. virtually any platform.
  1567.  
  1568. I want to especially thank Levente Hársfalvi <TLC@mszi.pmmf.hu> for Commodore
  1569. 16 programming information, and for his ComLink program, which showed me that
  1570. you can also misuse the IEC bus for data transfers.
  1571.  
  1572.  
  1573. 8. CONTACTING THE AUTHORS
  1574.  
  1575. If you have any questions, suggestions, or anything, feel free to e-mail us,
  1576. Marko Mäkelä <Marko.Makela@HUT.FI> or Olaf Seibert <rhialto@mbfys.kun.nl>.
  1577. Olaf is the Amiga and PET expert, other questions should be directed to
  1578. Marko.  In case you prefer snail-mail, here is the address:
  1579.  
  1580.     Marko Mäkelä
  1581.     Sillitie 10 A
  1582.     01480 Vantaa
  1583.     Finland
  1584.  
  1585. (This file is formatted using the ISO 8859-1 (Latin 1) characters.  In case
  1586. your terminal displays some other character set, you will see the ä
  1587. characters (a-Umlaut, "a" with two dots on top of it) incorrectly.)
  1588.